home *** CD-ROM | disk | FTP | other *** search
/ Aminet 1 (Walnut Creek) / Aminet - June 1993 [Walnut Creek].iso / aminet / os20 / util / dirdb20.lha / DirDB.doc < prev    next >
Text File  |  1993-04-18  |  10KB  |  283 lines
  1. This archive contains version 2.0 of my "Directory Database" suite.
  2.  
  3. Please note these programs ALL require 2.04 or greater. :-)
  4.  
  5.  Contents :
  6.  ~~~~~~~~
  7.  
  8. The programs contained are :
  9.  
  10.   MakeDirDB
  11.   FindDBEntry
  12.   DBEntry
  13.  
  14. Also contained in this archive is Jonas Petersson's 'upd' program,
  15. which is an ARexx 8SVX sample server, and some scripts to use the
  16. Directory Database with your sound samples.
  17.  
  18.  
  19.  Purpose :
  20.  ~~~~~~~
  21.  
  22. These programs make and search databases created from Amiga directory
  23. trees. It is much faster to search one of these databases for a file,
  24. than it is to search the filesystem. Also, you can use these programs
  25. to do something with all the files which match a pattern, or with
  26. random files.
  27.  
  28.  
  29.  Uses :
  30.  ~~~~
  31.  
  32.  - Finding a file, when only part of its name is known
  33.  - Choosing a file at random
  34.   ++ Playing a random sound sample, either from a script (see the
  35.      examples), by a hot key (using FKey and the scripts) or
  36.      a cron program (and the scripts). My amiga plays a random
  37.      sound sample every quarter hour, between reasonable hours,
  38.      to keep me awake. Look for CyberCron.
  39.   ++ Choosing a random background picture (for WB3.0 or via NickPrefs).
  40.      1. Set up a directory of background images
  41.      2. Make a (hard) link to one of them,
  42.       eg. "MakeLink sys:BGPic.link sys:wbpics/Maddonna hard" :-)
  43.      3. Use WBPattern or NickPrefs WBPicture to load sys:BGPic.link
  44.        (for WBPattern, initially BGPic.link must be a picture,
  45.         rather than a link to a picture, as WBPattern resolves the link.
  46.         Copy a file to sys:BGPic.link, use WBPattern to load the picture,
  47.         and save your preferences, then use WBPattern again, load
  48.         a different picture, or no picture and Use this (this unlocks
  49.         BGPic.link) then delete BGPic.link, and use MakeLink to
  50.         replace it with a link to a picture file.)
  51.      4. In your startup-sequence, before IPrefs or NickPrefs,
  52.         insert the lines:
  53.       delete >NIL: sys:BGPic.link
  54.       utilities:dbentry >NIL: dh0:dirdbs/WBPics.db random
  55.         pre="makelink sys:BGPic.link " post=" hard" execute unique
  56.          (The last line was wrapped for readability, it should be
  57.           all one line)
  58.  
  59.  
  60.  Installation :
  61.  ~~~~~~~~~~~~
  62.  
  63.  1. Place the 3 programs somewhere on your path
  64.  2. Put the scripts somewhere on your path (s: comes to mind)
  65.  3. Execute the MakeDBPath script, specifying where you want
  66.     your database files to go. This script creates then
  67.     Env:db directory, sets up the Path variable there, and
  68.     duplicates the directory to EnvArc:, so it will be there
  69.     when you reboot.
  70.  4. Unpack and install upd, reading its documentation
  71.  
  72.  5. (Optional) Set up a cron to play sounds regularly, and
  73.     put the scripts on function keys using FKey. Set up a
  74.     function key with the upd Fade command to stop samples
  75.     if necessary.
  76.  
  77.  Maintenence :
  78.  ~~~~~~~~~~~
  79.  
  80. Directories change. It is necessary to reconstruct the databases
  81. occassionally. It is possible to automate this into a cron task,
  82. so that once a day, say at 1:15am, any databases you use are
  83. updated. Then again, you may only use the databases for non-essential
  84. tasks, so you can update them when you require.
  85.  
  86.  Environment Variables :
  87.  ~~~~~~~~~~~~~~~~~~~~~
  88.  
  89. These programs use a number of environment variables, which are kept
  90. in your Env:DB directory, which is created by the MakeDBPath script.
  91. These variables include a Path variable, which tells the programs where
  92. to look for your databases, a Seed variable, used by the Random Number
  93. generator, and initialised based on the system time, first time they
  94. are run. Also, each call to DBEntry sets up variables containing the
  95. last file name, and its position in the database.
  96.  
  97.  History :
  98.  ~~~~~~~
  99.  
  100. Version 2.0 improves on the previous (unnumbered) version buy
  101. moving the random seed, and the 'Unique' function into the databases.
  102.  
  103. This has two benefits:
  104.  1. Speed at closure. The random seed is written to the database
  105.     instead of to ENV: and ENVARC:, which is quicker
  106.  2. True unique selection across multiple calls of DBEntry.
  107.     If you are using DBEntry to play random sounds, this means that
  108.     you will get random sounds, with no sound repeated until all
  109.     the sounds named in your database have been played. You should
  110.     update all calls to DBEntry in your scripts, etc, to include
  111.     the 'Unique' keyword.
  112.  
  113. The Version 2.0 programs can read the old databases, while the old
  114. programs cannot read the 2.0 databases.
  115.  
  116. -----------
  117.  
  118. MakeDirDB :
  119.  
  120. Makes a database containing all the file names in the specified
  121. directory/directories and their subdirectories.
  122.  
  123. Usage :
  124.  MakeDirDB DIR/M/A,DEST/A,PATTERN/K
  125.  
  126. Notes -
  127.  The database will contain any assigns specified in the Dir
  128. specification, but MakeDirDB cannot handle multiple path assigns.
  129. The assigns must be present when the database is referenced.
  130.  
  131. The Pattern defaults to #?, you might like to specify something
  132. like ~(#?.info) to exclude icons. You must use the Pattern keyword
  133. to specify this parameter (sorry I missed this in the old documentation).
  134.  
  135. For example,
  136.   MakeDirDB Sounds: sys:DBDir/Sounds.db Pattern=~(#?.info)
  137.  
  138. -----------
  139.  
  140. FindDBEntry :
  141.  
  142. Finds all occurences of a pattern in specified directory database(s).
  143. Optionally do something with the found names.
  144.  
  145. Usage :
  146.  FindDBEntry  DIRDB/A/M,PAT=PATTERN/A,PRE=PREPEND/K,POST=APPEND/K,NOLINE/S,
  147.               EXECUTE/S,INFO/S,NOTINMEM/S,FULL/S,DIRS/S,NOFILES/S
  148.  
  149. Arguments :
  150.  
  151.  DIRDB/A/M :
  152.     Specifies the databases to search. See note later on
  153.     Environment Variables, and Paths.
  154.  
  155.  PAT=PATTERN/A :
  156.     Specifies the DOS pattern to search using.
  157.     By default, just searches filenames. You can specify directories in
  158.     the pattern, and even patterns in the directory part.
  159.     Examples
  160.        #?foo#?         matches anything with foo in its name.
  161.        #?bar#?/#?foo#? matches anything with foo in its name, which is in a
  162.                        directory containing bar in its name.
  163.  
  164.  PRE=PREPEND/K :
  165.     Specfies text to place before the result in the output.
  166.  POST=APPEND/K :
  167.     Specfies text to place after the result in the output.
  168.  
  169.     Examples :
  170.        prepend="type "
  171.        -- will type all matching files
  172.        pre="rx *"address play 'file' '" post="' '-S'*""
  173.        -- uses upd to play the resulting sound samples.
  174.           *'s are used to insert the quotes in a DOS commandline
  175.  
  176.  NOLINE/S :
  177.     When printing the results, don't put each on a new line.
  178.  
  179.  EXECUTE/S :
  180.     Instead of printing the results to the console, execute each line of
  181.     output (including pre and post strings) as DOS commands.
  182.  
  183.  INFO/S :
  184.     Output how many files are in the DataBase
  185.  
  186.  NOTINMEM/S :
  187.     Don't load the full database into memory before searching.
  188.     Greatly decreases speed, but saves memory, equal to
  189.     the size of the DB file.
  190.  
  191.  FULL/S :
  192.     Matches the pattern against the full file path, rather than just the
  193.     file name. This is done automatically if the pattern contains a '/'.
  194.     This option allows the pattern to match directory names, and so
  195.     anything in that directory.
  196.  
  197.  DIRS/S :
  198.     If a directory matches the pattern, it's full name is output.
  199.  
  200.  NOFILES/S :
  201.     Use with DIRS to search only for matching directories.
  202.  
  203.  
  204. -------
  205.  
  206. DBEntry :
  207.  
  208.  DBEntry DIRDB/A,PRE=PREPEND/K,POST=APPEND/K,NUM/N,RANDOM/S,NOLINE/S,
  209.          SPEC=SPECIFIC/N/K,EXECUTE/S,STARTRANGE/K/N,ENDRANGE/K/N,
  210.          LAST/S,NEXT/S,WRAP/S,INFO/S,INMEM/S,UNIQUE/S
  211.  
  212.  DIRDB/A/M :
  213.     Specifies the databases to search. See note later on
  214.     Environment Variables, and Paths.
  215.  
  216.  PRE=PREPEND/K :
  217.     Specfies text to place before the result in the output.
  218.  POST=APPEND/K :
  219.     Specfies text to place after the result in the output.
  220.  
  221.     Examples :
  222.        prepend="type "
  223.        -- will type all matching files
  224.        pre="rx *"address play 'file' '" post="' '-S'*""
  225.        -- uses upd to play the resulting sound samples.
  226.           *'s are used to insert the quotes in a DOS commandline
  227.  
  228.  NUM/N :
  229.     Specifies how many file names to output, see RANDOM
  230.  
  231.  RANDOM/S :
  232.     Choose the file names to output at random. If not specified,
  233.     DBEntry will just start at the first (or nth if SPECIFIC is
  234.     specified) and proceed linearly through the entries.
  235.     See UNIQUE.
  236.  
  237.  NOLINE/S :
  238.     When printing the results, don't put each on a new line.
  239.  
  240.  SPEC=SPECIFIC/N/K :
  241.     Specifies a starting point in the database, or the specific
  242.     entry to output if NUM is not specified or equals 1
  243.  
  244.  EXECUTE/S :
  245.     Instead of printing the results to the console, execute each line of
  246.     output (including pre and post strings) as DOS commands.
  247.  
  248.  STARTRANGE/K/N
  249.  ENDRANGE/K/N :
  250.     Limit the range to choose from with RANDOM
  251.  
  252.  LAST/S
  253.  NEXT/S :
  254.     Various information is stored in environment variables.
  255.     These options use that information to select the most recent entry,
  256.     or the one after that.
  257.     As DBs are kept in alphabetic order, by subdirectory, this can
  258.     play the next sound in a subtopic.
  259.  
  260.  WRAP/S :
  261.     If you specify a large number, or -1 to NUM, and there aren't that
  262.     many entries, wrap back to the start.
  263.  
  264.  INFO/S :
  265.     Output how many files are in the DataBase
  266.  
  267.  INMEM/S :
  268.     Load the full database into memory. Don't use for one-offs, but
  269.     if you are fetching multiple entries, saves time at the expense
  270.     of memory, equal to the size of the DB file.
  271.     Note the difference to the option for FindDBEntry.
  272.  
  273.  UNIQUE/S :
  274.     Makes sure entries are only selected once each, until all entries
  275.     in the database have been selected.
  276.  
  277.     This option (now) survives repeated calls to DBEntry on the same
  278.     database. Any use of DBEntry with 'Unique' may not select a
  279.     particular file, as that file was selected previously.
  280.     
  281.     Unique works even when Random was not specified.
  282.  
  283.